استقبال وحفظ خيارات (وبيانات) الإضافة من خلال التعامل مع Setting API وOptions API في ووردبريس

تُعد الإضافات (Plugins) في نظام إدارة المحتوى ووردبريس إحدى أقوى ركائزه التي تتيح للمطورين توسيع وظائف النظام بما يتجاوز إمكاناته الأصلية. ومن بين المهام الأساسية التي تقوم بها الإضافات هي استقبال وتخزين البيانات والإعدادات الخاصة بها بطريقة آمنة وفعالة. لتحقيق ذلك، يوفر ووردبريس آليتين قويتين هما Setting API وOptions API، واللتان تشكلان معًا بنية تحتية متكاملة تسمح بإدارة الخيارات والإعدادات الخاصة بالإضافات بطريقة منهجية ومتوافقة مع بنية النظام.

هذا المقال يتناول بشكل موسّع كيفية استخدام هاتين الأداتين، مبينًا مفاهيمهما الأساسية، وآلية العمل، والخطوات العملية، فضلاً عن الاعتبارات الأمنية والتنظيمية، مع عرض نموذج تطبيقي يعزز الفهم العملي.

أولًا: مقدمة عن خيارات ووردبريس

يخزن ووردبريس الإعدادات والخيارات المختلفة التي تتحكم في سلوك الموقع والإضافات والثيمات في جدول wp_options ضمن قاعدة البيانات. يشكل هذا الجدول قاعدة مركزية تُستخدم بواسطة النظام لتخزين:

• إعدادات الإضافات.

• إعدادات القالب النشط.

• إعدادات النظام العامة (اسم الموقع، البريد، اللغة…).

• بيانات موقّتة (transients).

• قيم الكاش.

يوفر ووردبريس طبقة وسيطة للتعامل مع هذا الجدول وهي Options API، وأداة تنظيمية لإعداد صفحات الإعدادات وتسجيل الحقول وهي Settings API.

ثانيًا: Options API – واجهة التعامل المباشر مع خيارات قاعدة البيانات

تُعتبر Options API أداة أساسية للتخزين والاسترجاع المباشر لقيم الخيارات (Options) المخزنة في جدول wp_options.

أهم دوال Options API

مثال عملي:

php
CopyEdit
// إضافة خيار جديد
add_option( 'my_plugin_option', 'default_value' );

// استرجاع الخيار
$value = get_option( 'my_plugin_option' );

// تحديث الخيار
update_option( 'my_plugin_option', 'new_value' );

// حذف الخيار
delete_option( 'my_plugin_option' );

مزايا استخدام Options API:

• تُجري التخزين باستخدام API موحد وآمن.

• تُخزَّن الخيارات مؤقتًا في كاش داخلي لتحسين الأداء.

• تُنظَّم تلقائيًا ضمن جدول موحد، مما يسهل النسخ الاحتياطي والاستعادة.

ثالثًا: Settings API – واجهة إنشاء صفحات إعدادات منظمة

تمثل Settings API منهجية كاملة لبناء صفحات إعدادات داخل لوحة تحكم ووردبريس بطريقة متوافقة مع المعايير. تسمح للمطور بإنشاء:

• صفحات إعدادات.

• أقسام داخل الصفحات.

• حقول داخل الأقسام.

• آلية لحفظ البيانات.

المكونات الأساسية لـ Settings API:

1. تسجيل الإعدادات (register_setting)

2. إضافة قسم (add_settings_section)

3. إضافة حقل (add_settings_field)

4. عرض النموذج باستخدام دالة settings_fields()

خطوات العمل:

1. تسجيل الإعدادات:

php
CopyEdit
register_setting( 'my_plugin_settings_group', 'my_plugin_option_name' );

2. إضافة قسم إعدادات:

php
CopyEdit
add_settings_section(
    'my_section_id',
    'عنوان القسم',
    'my_section_callback',
    'my_plugin_settings_page'
);

3. إضافة حقل داخل القسم:

php
CopyEdit
add_settings_field(
    'my_field_id',
    'عنوان الحقل',
    'my_field_callback',
    'my_plugin_settings_page',
    'my_section_id'
);

4. عرض نموذج الحفظ داخل صفحة الإعدادات:

php
CopyEdit
"post" action="options.php">
    
        settings_fields( 'my_plugin_settings_group' );
        do_settings_sections( 'my_plugin_settings_page' );
        submit_button();
    ?>

مثال تطبيقي مكتمل:

php
CopyEdit
add_action( 'admin_menu', 'my_plugin_menu' );
add_action( 'admin_init', 'my_plugin_settings_init' );

function my_plugin_menu() {
    add_options_page(
        'إعدادات الإضافة',
        'إضافتي',
        'manage_options',
        'my_plugin',
        'my_plugin_settings_page'
    );
}

function my_plugin_settings_page() {
    ?>
    
class="wrap">
        <h1>إعدادات الإضافةh1>
        <form method="post" action="options.php">
            php
                settings_fields( 'my_plugin_group' );
                do_settings_sections( 'my_plugin' );
                submit_button();
            ?>
        form>
    div>
    php
}

function my_plugin_settings_init() {
    register_setting( 'my_plugin_group', 'my_plugin_option' );

    add_settings_section(
        'my_plugin_section',
        'القسم الرئيسي',
        null,
        'my_plugin'
    );

    add_settings_field(
        'my_plugin_field',
        'خانة الإدخال',
        'my_plugin_field_render',
        'my_plugin',
        'my_plugin_section'
    );
}

function my_plugin_field_render() {
    $value = get_option( 'my_plugin_option', '' );
    echo 'esc_attr( $value ) . '" />';
}

رابعًا: المقارنة بين Options API و Settings API

خامسًا: الاعتبارات الأمنية في استخدام APIs

عند التعامل مع البيانات من المستخدمين، يجب اتباع عدد من الضوابط الأمنية للحماية من الهجمات مثل XSS وCSRF:

• استخدام esc_attr() أو esc_html() عند الطباعة داخل HTML.

• استخدام sanitize_text_field() أو sanitize_email() لتنقية البيانات المدخلة قبل الحفظ.

• التأكد من وجود التحقق من الصلاحيات باستخدام current_user_can().

• استخدام دالة settings_fields() في النموذج لضمان التحقق من nonce.

سادسًا: حفظ خيارات متعددة في خيار واحد (Array)

يُفضّل في بعض الحالات تخزين خيارات متعددة ضمن خيار واحد بشكل مصفوفة لتقليل عدد العمليات على قاعدة البيانات.

php
CopyEdit
$options = get_option( 'my_plugin_options' );
$some_value = isset( $options['some_key'] ) ? $options['some_key'] : '';

ثم في الحفظ:

php
CopyEdit
$options = [
    'some_key' => sanitize_text_field( $_POST['some_key'] ),
    'another_key' => intval( $_POST['another_key'] ),
];
update_option( 'my_plugin_options', $options );

سابعًا: استخدام الجداول لتوضيح الحقول وعلاقتها بالإعدادات

مثال توضيحي:

ثامنًا: الاعتبارات العامة عند تصميم نظام الإعدادات

• تجنب التكرار: لا تقم بإنشاء خيارات متكررة، بل اجمع البيانات المتقاربة في مصفوفات داخل خيار واحد.

• احترام المعايير البصرية: استخدم CSS الخاص بووردبريس (classes مثل regular-text و form-table) لضمان تناسق العرض.

• استخدام الصفحات الفرعية: في حال كانت الإعدادات كثيرة، أنشئ صفحات فرعية باستخدام add_submenu_page().

• توفير افتراضيات: استخدم القيم الافتراضية داخل get_option() لتجنب ظهور أخطاء عند غياب الإعداد.

تاسعًا: تخزين الخيارات في شبكة المواقع (Multisite)

إذا كنت تطور إضافة تعمل في بيئة WordPress Multisite، فإن ووردبريس يوفر دوال بديلة للتعامل مع الخيارات على مستوى الشبكة:

عاشرًا: أهم المصادر والمراجع

• WordPress Codex – Settings API

• WordPress Developer Resources – Options API

من خلال الدمج الذكي بين Options API وSettings API، يستطيع مطوّر ووردبريس إنشاء أنظمة إعدادات متقدمة وقابلة للتوسع، تلبي احتياجات الاستخدام العملي مع المحافظة على البنية القياسية للنظام. يسمح ذلك بتطوير إضافات أكثر تنظيمًا، وأكثر أمانًا، وأسهل في الاستخدام من قِبل المستخدم النهائي.